import { PackageManagerTabs } from '@theme';

# Modern.js Module

本章节介绍如何将使用 Modern.js Module 的项目迁移到 Rslib。

## 调整 package.json

`Rslib` 的依赖链路非常短。对于基本功能，你只需要使用 `@rslib/core` 包。

你可以通过 [快速开始](/guide/start/quick-start) 创建一个 Rslib 项目，然后更新你的 `package.json` 文件，如下所示：

- 移除 `main`, `lint-staged`, `simple-git-hooks`, `sideEffects` 和 `publishConfig` 字段
- 将 `types` 字段从 `./dist/types/index.d.ts` 改为 `./dist/index.d.ts`
- 将 `module` 字段从 `./dist/es/index.js` 改为 `./dist/index.js`
- 移除 `prepare`, `build:watch`, `reset`, `change`, `bump`, `pre`, `change-status`, `gen-release-note`, `release`, `new`, `upgrade` 脚本
- 将 `build` 脚本从 `modern build` 改为 `rslib build`
- 将 `dev` 脚本从 `modern dev` 改为 `rslib build --watch`
- 将 `lint` 脚本名称改为 `check` 并保持其值
- 添加一个新脚本 `format` 并设置其值为 `biome format --write`
- 添加一个新脚本 `test` 并设置其值为 `vitest run`
- 添加 `exports` 字段 (object)
  - 添加 `"."` (object)
  - 添加 `"types": "./dist/index.d.ts"` 和 `"import": "./dist/index.js"` 字段
- 添加 `files` 字段并设置其值为 `["dist"]`
- 根据你的配置和使用情况，`devDependencies` 可能会有所不同
  - 重要提示：将 `@modern-js/module-tools` 替换为 `@rslib/core`
  - 我们不再需要 `rimraf`, `lint-staged` 和 `simple-git-hooks` 了
- 复制你需要的 `dependencies` 和 `peerDependencies` 字段

你的 `package.json` 文件应该如下所示：

```json title="package.json"
{
  "name": "rslib",
  "version": "1.0.0",
  "type": "module",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    }
  },
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "files": ["dist"],
  "scripts": {
    "build": "rslib build",
    "check": "biome check --write",
    "dev": "rslib build --watch",
    "format": "biome format --write",
    "test": "vitest run"
  },
  "devDependencies": {
    "@biomejs/biome": "^2.0.0",
    "@rslib/core": "^0.1.3",
    "typescript": "^5.6.3",
    "vitest": "^2.1.8"
  },
  "peerDependencies": {},
  "dependencies": {}
}
```

## 调整打包配置

现在我们有了一个干净的起点。我们将继续使用 `Rslib` 配置。它遵循所有 `Rs*` 项目的相同模式。由于此步骤对于每个人来说都不同，下面是一个基本的示例：

将你的 `modern.config.ts` 文件替换为 `rslib.config.ts` 文件：

```js title="rslib.config.ts"
import { defineConfig } from '@rslib/core';

export default defineConfig({
  source: {
    entry: {
      index: ['./src/**'],
    },
  },
  lib: [
    {
      bundle: false,
      dts: true,
      format: 'esm',
    },
  ],
});
```

## TypeScript 类型定义

如果你在 `Modern.js Module` 中使用 TypeScript 并需要生成类型定义文件，请添加以下更改：

```js title="rslib.config.ts"
import { defineConfig } from '@rslib/core';

export default defineConfig({
  //...
  lib: [
    {
      //...
      dts: true,
    },
  ],
});
```

## React

如果你在 `Modern.js Module` 中使用 React，请添加以下更改：

```js title="rslib.config.ts"
import { defineConfig } from '@rslib/core';
// 快速提示：你可以在这里使用所有 Rsbuild 插件，因为它们与 Rslib 兼容
import { pluginReact } from '@rsbuild/plugin-react';

export default defineConfig({
  //...
  output: {
    target: 'web',
  },
  plugins: [pluginReact()],
});
```

此外，你需要安装 `@rsbuild/plugin-react` 包作为 `devDependencies`。

<PackageManagerTabs command="add @rsbuild/plugin-react -D" />

## Sass

如果你在 `Modern.js Module` 中使用 Sass，请添加以下更改：

```js title="rslib.config.ts"
import { defineConfig } from '@rslib/core';
// 快速提示：你可以在这里使用所有 Rsbuild 插件，因为它们与 Rslib 兼容
import { pluginSass } from '@rsbuild/plugin-sass';

export default defineConfig({
  //...
  plugins: [pluginSass()],
});
```

此外，你需要安装 `@rsbuild/plugin-sass` 包作为 `devDependencies`。

<PackageManagerTabs command="add @rsbuild/plugin-sass -D" />

如果你在运行 TypeScript 和 Sass，你可能会遇到类型声明文件生成错误。这可以通过在 `/src` 目录中添加一个 `env.d.ts` 文件来解决。

```ts title="src/env.d.ts"
declare module '*.scss' {
  const content: { [className: string]: string };
  export default content;
}
```

或者

```ts title="src/env.d.ts"
/// <reference types="@rslib/core/types" />
```

## CSS Modules

如果你在 `Modern.js Module` 中使用 CSS Modules，请添加以下更改：

```js title="rslib.config.ts"
import { defineConfig } from '@rslib/core';
import { pluginSass } from '@rsbuild/plugin-sass';

export default defineConfig({
  lib: [
    {
      //...
      output: {
        cssModules: {
          // CSS Modules 选项与官方 "css-modules" 包中的选项完全相同
          localIdentName: '[local]--[hash:base64:5]',
        },
      },
    },
  ],
  plugins: [pluginSass()],
});
```

## 内容补充

此迁移文档由社区用户 [YanPes](https://github.com/YanPes) 贡献。非常感谢他的贡献！
